<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Save : DataMapper User Guide</title>

<style type='text/css' media='all'>@import url('../css/userguide.css');</style>
<link rel='stylesheet' type='text/css' media='all' href='../css/userguide.css' />

<meta http-equiv='expires' content='-1' />
<meta http-equiv= 'pragma' content='no-cache' />
<meta name='robots' content='all' />

</head>

<body>

<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"></div></div>
<div id="nav2"><a name="top">&nbsp;</a><a id="nav_toggle" href="#"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>DataMapper</h1></td>
<td id="breadcrumb_right"><a href="toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->

<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="http://stensi.com/">DataMapper Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
Save
</td>
</tr>

</table>
<!-- END BREADCRUMB -->

<br clear="all" />


<!-- START CONTENT -->
<div id="content">


<h1>Save</h1>

<p>There are a number of ways to run Save and its effect will be different depending on the condition of the object you run it on, and whether you pass in a parameter.</p>

<h2>Save on a New Object</h2>
<p>Running Save on a new object, one without an ID, will see a new record created for it its relevant Database table.  After saving, it will automatically populate itself with its new data, such as its ID and any changes its properties had after validation (such as an encrypted password).</p>
<code>
// Create new User<br />
$u = new User();<br />
<br />
// Enter values into required fields<br />
$u->username = "foo";<br />
$u->password = "bar";<br />
$u->email = "foo@bar.com";<br />
<br />
// Save new user<br />
$u->save();
</code>

<p>The new user <b>foo</b> will now have an ID and an encrypted password (as well as a salt for use later on when he logs in).</p>

<h2>Save on an Existing Object</h2>
<p>Running Save on an existing object will update its corresponding record in the database.</p>
<code>
// Get user foo<br />
$u = new User();<br />
$u->where('username', 'foo')->get();<br />
<br />
// Change the email<br />
$u->email = "baz@qux.com";<br />
<br />
// Save changes to existing user<br />
$u->save();
</code>

<p>As the only change is the email, the email will be updated.</p>


<h2>Save a Relationship</h2>

<p>It's easy to save the relationships your objects have with each other, and there are a few ways of doing it.</p>

<p class="important"><strong>Note:</strong>&nbsp; When saving a relationship on an object, the object itself is also saved.</p>

<h3>Save a Single Relation</h3>

<p>To save a relation, you pass the object you want to relate to, into your current object.</p>

<code>
// Get user foo<br />
$u = new User();<br />
$u->where('username', 'foo')->get();<br />
<br />
// Get country object for Australia<br />
$c = new Country();<br />
$c->where('name', 'Australia')->get();<br />
<br />
// Relate user foo to country Australia<br />
$u->save($c);<br />
</code>

<h3>Save Multiple Relations</h3>

<p>To save multiple relations, you pass an object's all property or an array of objects.</p>
<code>
// Get user foo<br />
$u = new User();<br />
$u->where('username', 'foo')->get();<br />
<br />
// Get country object for Australia<br />
$c = new Country();<br />
$c->where('name', 'Australia')->get();<br />
<br />
// Get a number of books from the year 2000<br />
$b = new Book();<br />
$b->where('year', 2000)->get();<br />
<br />
// Get a movie with ID of 5<br />
$m = new Movie();<br />
$m->where('id', 5)->get();<br />
<br />
// Relate user foo to all the books<br />
$u->save($b->all);<br />
<br />
// Or we could pass everything in one go (it's ok to have a mix of single objects and all lists from objects)<br />
$u->save(array($c, $b->all, $m));<br />
</code>

<h3>Save a New object and its Relations in a single call</h3>

<p>It is important to note that you can save both an object's data and relationships with a single save call.  For example, you could save a new object and its relationships all in one go like this:</p>
<code>
// Create new User<br />
$u = new User();<br />
<br />
// Enter values into required fields<br />
$u->username = "foo";<br />
$u->password = "bar";<br />
$u->email = "foo@bar.com";<br />
<br />
// Get country object for Australia<br />
$c = new Country();<br />
$c->where('name', 'Australia')->get();<br />
<br />
// Save new user and also save a relationship to the country<br />
$u->save($c);
</code>

<h3>Save an Existing object and its Relations in a single call</h3>

<p>In the same way, you can update an existing records data as well as its relationships with a single save call.</p>

<code>
// Get user foo<br />
$u = new User();<br />
$u->where('username', 'foo')->get();<br />
<br />
// Change the email<br />
$u->email = "baz@qux.com";<br />
<br />
// Get country object for United States<br />
$c = new Country();<br />
$c->where('name', 'United States')->get();<br />
<br />
// Update email and update the relationship to country United States<br />
$u->save($c);<br />
</code>


</div>
<!-- END CONTENT -->


<div id="footer">
<p>
Previous Topic:&nbsp;&nbsp;<a href="getcopy.html">Get Copy</a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href="delete.html">Delete</a>
</p>
<p><a href="http://stensi.com">DataMapper</a> &nbsp;&middot;&nbsp; Copyright &#169; 2008 &nbsp;&middot;&nbsp; <a href="http://stensi.com/">Simon Stenhouse</a></p>
<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006-2008 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
</div>

<script type="text/javascript" src="../js/mootools.js"></script>
<script type="text/javascript" src="../js/menu.js"></script>
<script type="text/javascript">
<!--
	window.addEvent('domready', function() {

		// Create Menu
		var menu = new Menu({
			basepath: '../',
			pagepath: ''
		});

	});	
//-->
</script>
</body>
</html>